home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / dirut / dosdir21.zip / DIRENT.MAN < prev    next >
Encoding:
Text File  |  1994-06-22  |  2.8 KB  |  89 lines
  1. DIRECTORY(1V)          C LIBRARY FUNCTIONS          DIRECTORY(1V)
  2.  
  3. NAME
  4.      opendir, readdir, rewinddir, closedir - directory operations
  5.  
  6. SYNOPSIS
  7.      #include "dirent.h"
  8.  
  9.      DIR *opendir(dirname)
  10.      char *dirname;
  11.  
  12.      struct dirent *readdir(dirp)
  13.      DIR *dirp;
  14.  
  15.      void rewinddir(dirp)
  16.      DIR *dirp;
  17.  
  18.      int closedir(dirp)
  19.      DIR *dirp;
  20.  
  21. DESCRIPTION
  22.      opendir() opens the directory named by dirname  and  associ-
  23.      ates  a  directory  stream  with  it.   opendir()  returns a
  24.      pointer to be used to identify the directory stream in  sub-
  25.      sequent  operations.   A NULL pointer is returned if dirname
  26.      cannot be accessed or is not a directory, or  if  it  cannot
  27.      malloc enough memory to hold the whole thing.
  28.  
  29.      readdir() returns a pointer to the next directory entry.  It
  30.      returns  NULL  upon  reaching  the  end  of the directory or
  31.      detecting an invalid seekdir() operation.
  32.  
  33.      rewinddir() resets  the  position  of  the  named  directory
  34.      stream to the beginning of the directory.  It also causes the
  35.      directory stream to  refer  to  the  current  state  of  the
  36.      corresponding  directory,  as a call to opendir() would have
  37.      done.
  38.  
  39.      closedir() closes the named directory stream and  frees  the
  40.      structure associated with the DIR pointer.
  41.  
  42. NOTES
  43.      An open directory must always be closed with the closedir() function
  44.      to ensure the next attempt to open that directory is successful.
  45.  
  46. RETURN VALUES
  47.      opendir() returns a pointer to an object of type DIR on suc-
  48.      cess.   On  failure, it returns NULL and sets errno to indi-
  49.      cate the error.
  50.  
  51.      readdir() returns a pointer to  an  object  of  type  struct
  52.      dirent  on  success.   On  failure, it returns NULL and sets
  53.      errno to indicate the error.  When the end of the  directory
  54.      is  encountered,  readdir()  returns  NULL  and leaves errno
  55.      unchanged.
  56.  
  57.      closedir() returns:
  58.  
  59.      0    on success.
  60.  
  61.      -1      on failure and sets errno to indicate the error.
  62.  
  63. ERRORS
  64.      If any of the following  conditions  occur,  opendir()  sets
  65.      errno to:
  66.  
  67.      ENOMEM    Not enough memory to allocate a DIR object.
  68.  
  69.      ENOENT    The named directory does not exist.
  70.  
  71.      For each of the following conditions, when the condition  is
  72.      detected, readdir() and closedir() set errno to the following:
  73.  
  74.      EBADF    dirp does not refer to an open directory stream.
  75.  
  76. EXAMPLES
  77.      Sample code which searchs a directory for entry ``name'' is:
  78.  
  79.         dirp = opendir(".");
  80.         for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
  81.             if (!strcmp(dp->d_name, name)) {
  82.             closedir (dirp);
  83.             return FOUND;
  84.             }
  85.         closedir (dirp);
  86.         return NOT_FOUND;
  87.  
  88. MSDOS/VMS Release 1.1   Last change: 22 June 1994
  89.